feat: ship type declarations for @webjsdev/server (fix TS7016) - #322
Merged
Conversation
added 3 commits
June 3, 2026 21:05
@webjsdev/core shipped an index.d.ts + a types export condition, but
@webjsdev/server shipped neither, so under strict + nodenext a TS app's
import { createRequestHandler, cors, cache, ... } from '@webjsdev/server'
emitted TS7016 (no declaration file). That blocked the webjs typecheck-in-CI
story and left a core import untyped for every TS app. Ship a hand-authored
index.d.ts overlay typing every named export (precise for the high-traffic
public API, reusing core's PageProps/LayoutProps/RouteHandlerContext), plus
src/check.d.ts and src/testing.d.ts for the subpaths, and add types-first
export conditions. A drift guard asserts the overlay matches index.js's
runtime exports; a fixture + a TS7016 counterfactual prove the fix.
Closes #310
…sses
The Conventions CI step rejects any .ts under packages/{core,server,cli,
ts-plugin} that is not a .d.ts. The new type fixture was server-exports.test-d.ts
under packages/server/test/, whose name ends in .test-d.ts (not .d.ts), so the
buildless grep flagged it as TS source in a buildless package. Every other
.test-d.ts already lives at the repo-root test/types/ (outside packages/), so
move the fixture + its nodenext runner there to match the convention; the drift
guard stays near the package (a .mjs, which the grep ignores).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #310
Summary
@webjsdev/coreshipped anindex.d.ts+ atypesexport condition, but@webjsdev/servershipped neither. So understrict+nodenexta TypeScript app'simport { createRequestHandler, cors, cache, createAuth, rateLimit, sitemap, ... } from '@webjsdev/server'emitted TS7016 ("Could not find a declaration file for module"). That blocked thewebjs typecheck-in-CI story (a fresh scaffold would fail on the server import) and left a core import untyped for every TS app.This ships a hand-authored, types-only overlay (the runtime stays plain
.js+ JSDoc, zero runtime cost):packages/server/index.d.tstypes every named export ofindex.js. The high-traffic public API is precisely typed from each source's JSDoc (createRequestHandlerreturn shape,cache<T>preserving the wrapped signature +.invalidate(),cors/rateLimitreturningMiddleware,sitemap/sitemapIndexreturningstring,Session, therevalidate*family, the context helpers, the cache stores,createAuth/Credentials/Google/GitHub). It reuses core'sPageProps/LayoutProps/RouteHandlerContextrather than redefining, and definesActionResult<T>locally (core does not export it) matching the documented envelope. Lower-traffic internals get reasonable structural declarations, not blanketany.src/check.d.tsandsrc/testing.d.tstype the./checkand./testingsubpaths.index.d.tsre-exports the testing helpers viaexport *(they ship from both entry points) to avoid duplication.package.json: types-first export conditions for.,./check,./testing(nodenext requirestypesbeforedefault), the top-leveltypes, andindex.d.tsadded tofiles.Tests
test/types/): imports the documented surface and USES it at real signatures understrict+nodenext(matching the scaffold's tsconfig), so a wrong signature fails compile.index.d.tsaside and asserts the bare import errors TS7016 with non-zero tsc, then restores it, proving the overlay is load-bearing. Before: tsc exit 2 (TS7016). After: exit 0.index.js's runtime exports, so a future export added without a type is caught.exportsedit did not break runtime resolution (all three subpaths stillimport()at runtime). The scaffold suite passes.Review
3 type tests green. A self-review found 4 type-accuracy nits (the
Session.datashape was confidently wrong,redisStore/SessionStorage.saveimprecise, a drift-test filename typo), all fixed and re-verified clean.Docs
packages/server/AGENTS.md(new type-overlay note),agent-docs/typescript.md(both runtime packages now ship a type overlay). I deliberately did NOT wirewebjs typecheckinto scaffold CI in this PR (a separate follow-up). This PR closes the declaration gap that blocked it.